Skip to content

Wes/core architecture rework - #2638

Merged
bwreid merged 16 commits into
mainfrom
wes/core-architecture-rework
Aug 5, 2026
Merged

Wes/core architecture rework#2638
bwreid merged 16 commits into
mainfrom
wes/core-architecture-rework

Conversation

@bwreid

@bwreid bwreid commented Aug 4, 2026

Copy link
Copy Markdown
Contributor

This PR breaks the Server page up into several different pages. The previous Server page has several different concepts within it, while this attempts to break it up into more manageable chunks that are a bit more readable and understandable. A general overview is below:


  • Overview — Frames the server as a thin coordination layer, not where logic lives. Compares agent-native's shape (server just does auth, migrations, and mounting actions) to a traditional app's (server holds business logic and data access). Points to Nitro/H3 as the underlying toolkit and links out to the other four pages plus a reminder to default to actions before writing custom routes.
    • Database — How to connect and use SQL. Covers the five hosting backends (SQLite default, PGlite for local Postgres, hosted Postgres/Neon/Supabase, Turso/libSQL, and a planned Builder.io-managed option), the three files every app needs (schema.ts, db/index.ts, plugins/db.ts), writing additive versioned migrations with runMigrations, scoping data with owner_email/ownableColumns()/accessFilter, the SQL-backed sync loop behind useDbSync(), and an escape hatch (getDbExec) for raw SQL.
    • Middleware — What server/middleware/ is and why the auth guard lives there instead of in a plugin (plugins only run at startup, not per-request, and the framework's own middleware registry doesn't cover page routes or custom /api/* routes). Shows the auth middleware file and how to add public paths via the auth plugin.
    • Plugins — Startup hooks in server/plugins/. Documents the two plugins every app ships (auth.ts, agent-chat.ts) plus the optional db.ts migrations plugin, how to write a custom plugin with defineNitroPlugin, and startup ordering (db → auth → agent-chat via alphabetical filename order).
    • Routes — File-based custom routes in server/routes/ vs. the framework-reserved /_agent-native/* namespace. Gives a decision table for when a custom route beats an action (webhooks, uploads, streaming, OAuth callbacks, public pages), a worked webhook example, naming conventions, how to scope a route to the request user with runWithRequestContext/accessFilter (since custom routes don't get auto request context like actions do), and the SSR catch-all route.

This does not yet include translations. I want to get this reviewed for content before spending the tokens on translations. :)

…in their frontmatter are hidden from the nav and return 404 when accessed directly unless VITE_SHOW_DRAFTS=true is set. In preview mode, draft nav items render in warning amber and draft pages show a callout banner.
@github-actions

github-actions Bot commented Aug 4, 2026

Copy link
Copy Markdown
Contributor

Here's a visual recap of what changed:

Visual recap

Open the full interactive recap

Large diff — this recap is a summarized view (top files + schema/API deltas).

builder-io-integration[bot]

This comment was marked as outdated.

@steve8708 steve8708 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

great stuff wes - may have some localized mdx we need to update/move too

bwreid added 9 commits August 5, 2026 12:48
oxfmt --check was failing on this extra blank line.
Adds five new draft MDX pages (server-overview, server-database,
server-middleware, server-plugins, server-routes) and an Agents
placeholder, wired into the nav under a draft Server group. Pages
are hidden in production and visible with VITE_SHOW_DRAFTS=true.

Includes nav keys in all locale files and an updated i18n doc-coverage
baseline to exempt draft pages from the localized-doc requirement.
Reframes db.ts as optional rather than default, moves the database
plugin section after auth and agent-chat, expands the intro to explain
what plugins are and how Nitro discovers them, and adds a new section
on writing custom plugins with defineNitroPlugin linking to Nitro docs.
…are guide

Expands the draft from a stub into a full page:
- Adds a diagram showing callers → middleware → allowed/blocked outcomes
- Rewrites the intro to describe middleware as a general cross-cutting layer
- Adds a "Writing Middleware" section with a defineEventHandler example and
  links to Nitro/H3 docs, placed before the auth section
- Consolidates The Auth Guard, Why Middleware, and Adding Public Paths under
  a single "The Auth Middleware" H2 with those as H3 subheadings
…agram

Reorganizes the draft from a loosely ordered reference into a narrative
that builds from concept to implementation:
- New diagram showing Browser/UI and Agent loop reaching the database
  through the same Actions layer
- Hosting Options section covering all five backends in order of
  complexity (SQLite default, PGlite, Postgres, Turso, Builder managed)
- Setting Up section as four numbered steps: define schema, create DB
  client, write migrations, query in actions
- Scoping Data to Users consolidates the owner_email and ownableColumns
  patterns that were previously scattered
- Removes all em-dashes throughout in favor of separate sentences
Ports the sync loop content from the published server.mdx into the
database page, where it completes the write story: after an action
mutates data, the sync version increments and useDbSync() on the client
invalidates caches so the UI refreshes. Includes the sync loop diagram
and the poll endpoint block. Adds a What's next link to real-time-sync.
Splits server.mdx into five pages (overview, database, middleware,
plugins, routes), un-drafts them in the nav, and repoints cross-page
links across the docs that pointed at the old combined page.
Translates the 5 server-*.mdx docs (overview, database, middleware,
plugins, routes) into ar-SA, de-DE, es-ES, fr-FR, hi-IN, ja-JP, ko-KR,
pt-BR, zh-CN, and zh-TW, replacing verbatim English copies left over
from the Server section split.

- Remove the old single-page server.mdx from every locale; it has no
  English source counterpart since the split and was unreachable.
- Translate the Server dropdown's sidebar labels (Overview, Middleware,
  Plugins, Routes, and Server itself for ar-SA/hi-IN) so the nav
  structure matches across locales.
- Fix a stale content/server.md reference in docs/AGENTS.md.
- Drop 50 now-stale entries from the doc-coverage baseline and add
  "Agent Native" to the no-translate-terms allowlist so the guard
  no longer flags the brand name as an untranslated string.
- Point the Real-Time Sync link at the existing key-concepts#polling-sync
  anchor instead of the non-existent /docs/real-time-sync slug.
- server-database.mdx copied its diagram/AnnotatedCode/DataModel blocks
  from database.mdx without regenerating their ids, so three blocks
  collided with database.mdx's own blocks of the same id. Assign each
  a unique id.

Applies to the English source and all 10 locale translations, which
mirrored the same bugs.
@bwreid
bwreid force-pushed the wes/core-architecture-rework branch from a95bb67 to ea56af6 Compare August 5, 2026 20:59
builder-io-integration[bot]

This comment was marked as outdated.

- Add a /docs/server -> /docs/server-overview redirect (both the default
  and localized slug routes) now that server.mdx is split into five pages.
- Teach stable migration names in server-database.mdx and
  server-plugins.mdx: version-only migrations collide across branches that
  reuse the same version number, which runMigrations' name-based tracking
  is designed to avoid.
- Correct server-plugins.mdx's startup-order section: default plugins load
  in lexical order (agent-chat.ts, auth.ts, db.ts), and Nitro does not await
  one plugin's async init before starting the next.
- Add explicit {#id} anchors to headings that relied on the ASCII-only
  heading slugger, which produced empty/duplicate anchors for non-Latin
  translations.
Base automatically changed from wes/draft-doc-option to main August 5, 2026 21:59
…-rework

# Conflicts:
#	packages/core/docs/content/agent-surfaces.mdx
#	packages/docs/app/routes/docs.$locale.$slug.tsx
#	packages/docs/app/routes/docs.$slug.tsx
#	scripts/i18n-localized-doc-coverage-baseline.txt
@netlify

This comment has been minimized.

@netlify

This comment has been minimized.

@netlify

This comment has been minimized.

@netlify

This comment has been minimized.

@netlify

This comment has been minimized.

@netlify

This comment has been minimized.

@netlify

This comment has been minimized.

@netlify

This comment has been minimized.

@netlify

This comment has been minimized.

@netlify

This comment has been minimized.

@netlify

This comment has been minimized.

@netlify

This comment has been minimized.

@netlify

This comment has been minimized.

@netlify

This comment has been minimized.

@netlify

This comment has been minimized.

@netlify

This comment has been minimized.

@netlify

This comment has been minimized.

@netlify

This comment has been minimized.

@builder-io-integration builder-io-integration Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Builder reviewed your changes and has a few items to flag 🟡

Review Details

Incremental Review Summary

The latest commit adds the localized versions of the split Server documentation and addresses two findings from the previous review: the duplicate block identifiers were changed to unique IDs, and both default and localized docs routes now redirect the legacy server slug to server-overview. Those fixes were verified and the corresponding review threads were resolved.

No new actionable findings were returned by the incremental review workers before the session was interrupted. Previously reported issues that remain open were not resubmitted: the missing /docs/real-time-sync target, the unsafe timingSafeEqual example, the SQLite-incompatible migration example, and the Agent Surfaces link whose target does not document the promised production handler signature. The newly added locale files are structurally aligned with the English split and the navigation now has localized page sources.

Risk assessment: Low risk — documentation, navigation, and localization changes only. 🧪 Browser testing: Will run after this review (PR touches docs UI/navigation code).

The new Server section .mdx files weren't run through oxfmt before commit.
@netlify

This comment has been minimized.

@netlify

This comment has been minimized.

@netlify

This comment has been minimized.

@netlify

This comment has been minimized.

@netlify

This comment has been minimized.

@netlify

This comment has been minimized.

@netlify

This comment has been minimized.

@netlify

This comment has been minimized.

@netlify

This comment has been minimized.

@netlify

This comment has been minimized.

@netlify

This comment has been minimized.

@netlify

This comment has been minimized.

@netlify

This comment has been minimized.

@netlify

This comment has been minimized.

@netlify

This comment has been minimized.

@netlify

This comment has been minimized.

@netlify

This comment has been minimized.

@netlify

This comment has been minimized.

@bwreid
bwreid merged commit f836d7e into main Aug 5, 2026
94 checks passed
@bwreid
bwreid deleted the wes/core-architecture-rework branch August 5, 2026 22:47
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants